
<h1 class="kf">Running Knopflerfish</h1>

<h2 class="kf">Starting Knopflerfish</h2>
The Knopflerfish OSGi framework is distributed as an executable jar
file and is started by running java on the
framework.jar file in the osgi directory. 
<pre class="shell">
    &gt; cd osgi
    &gt; java -jar framework.jar
</pre>
<p>
  The framework can also be started by double-clicking on the
  framework.jar file from Finder/Explorer or similar tools, depending on
  operating system used.
</p>
<p>
  The compact version of the framework is started the same way, but instead of 
  framework.jar the framework_compact.jar file must be used, e.g.
<pre class="shell">
    &gt; cd osgi
    &gt; java -jar framework_compact.jar
</pre>
</p>

<p>
  It is also possible to start Knopflerfish from the 
  <a href="building.html">
    ant build environment.
  </a>
  This is typically done when running the 
  <a href="testing.html">
    Knopflerfish test suite.
  </a>
</p>
<p>
  The SDK installation starts a default set of bundles, including the 
  <a href="bundledoc/index.html?docpage=desktop/index.html">
    Knopflerfish OSGi Desktop bundle
  </a> and other utilities. 
</p>
The Knopflerfish framework can be further controlled by:
<ul>
  <li><a href="#options">Supplying command line options</a></li>
  <li><a href="#xargs">Creating xargs file</a></li>
  <li><a href="#props">Setting framework and system properties</a></li>
</ul>

For a complete description of all framework feature please refer to
the 
<a href="bundledoc/index.html?docpage=framework/index.html">
  framework bundle documentation
</a>.

<a name="options"></a>
<h2 class="kf">Knopflerfish command line options</h2>
To control the behavior of Knopflerfish OSGi command line options can
be supplied. To get help on the framework options, run the framework with the help option.
<pre class="shell">
    java -jar framework.jar -help
</pre>
This prints a help screen (exact contents is version dependent).

<pre class="shell">
java -jar framework.jar -help
Knopflerfish OSGi framework launcher, version 6.0.0.0001
Copyright 2003-2013 Knopflerfish. All Rights Reserved.
See https://www.knopflerfish.org for more information.

 Usage:  java [properties] org.knopflerfish.framework.Main [options]
      or java [properties] -jar framework.jar [options]
      or ./kf2 [options] [-- [properties]]  [--- [extra]] (*)

 Options:
   -exit          Exit the JVM process
   -help          Print this text and exit
   -version       Print version and exit
   -jvminfo       Print system and framework properties and exit
   -sleep SEC     Sleep a while before next command.
   -xargs file    Load more command line arguments from file, exit if file
                  cannot be loaded.
   --xargs file   Load more command line arguments from file, continue 
                  if file cannot be loaded (but print error)

   -create        Create and initialize a new framework instance
                  after a shutdown. The default is to reuse the old
                  framework instance.
   -ff FF         Specify the name of the FrameworkFactory to use when
                  creating the framework instance.
   -init          Start an empty platform (i.e., clear old presistent data).
   -launch        Launch framework (i.e., start it).
   -shutdown mSEC Shutdown framework, timeout in milliseconds.

   -install URL   Install a bundle
   -istart URL    Install and start bundle according to activation policy.
   -start ID      Start bundle (according to its activation policy)
   -start_e ID    Start bundle eagerly (i.e., ignore its activation policy)
   -start_et ID   Start bundle eagerly and transiently
   -start_pt ID   Start bundle transiently according to policy
   -stop ID       Stop bundle
   -stop_t ID     Stop bundle transiently (i.e, non-persistent stop)
   -uninstall ID  Uninstall a bundle
   -update ID     Update a bundle

   -initlevel N   Set initial start level for installed bundles
   -startlevel N  Set the beginning start level of the Start Level service

 Extra: (Only applicable when using ./kf2)
   -java PATH	  Use this JVM (Default=java)


 The default directory used for storing bundle data is  "fwdir".

 (*) Fully R4 compatible, enables support for bootclasspath extension bundles.

 For extended help and list of all available system properties, see online
 documentation or visit:

 https://www.knopflerfish.org/releases/current/docs/bundledoc/framework/index.html
</pre>

<a name="xargs"></a>
<h2 class="kf">xargs files</h2>
<p>
The xargs file are Knopflerfish command line options specified in a
text file, typically ending in .xargs. This is a convenient method for
specifying which bundles to start as well as setting framework
properties.
</p>
<p>
The Knopflerfish SDK includes the following .xargs files by default
<div class="kf">
  <dl>
    <dt>init.xargs</dt>
    <dd>
      Initial or bootstrap start. Also used as default if no other
      xargs argument is given. See also 
      <a href="bundledoc/index.html?docpage=framework/index.html#init_restart">
	Initial start vs restart
      </a>.
      <p>
	Generated from template.xargs.in (only present in a full
	source file installation).
      </p>
    </dd>
    <dt>headless.xargs</dt>
    <dd>
      Initial or bootstrap start to use when running the JVM is
      running in headless mode. Same set of bundles as in init.xargs
      except that bundles requiring AWT has been commented out.
      <p>
	Generated from template.xargs.in (only present in a full
	source file installation) with "$(AWT)" set to '#'.
      </p>
    </dd>
    <dt>minimal.xargs</dt>
    <dd>
      Starts the framework and a minimal set of bundles.
    </dd>
    <dt>props.xargs</dt>
    <dd>
      One common xargs file that only set properties. Is used, or sourced, by
      other xargs files.
    </dd>
    <dt>remote-init.xargs</dt>
    <dd>
      Initial and bootstrap start with bundles loaded from an HTTP
      URL from a release specific bundle repository, located on www.knopflerfish.org,
      instead of loading from a file URL from the installation.
    </dd>
    <dt>init-tests.xargs</dt>
    <dd>
      xargs file for the Knopflerfish test suite. Normally invoked
      via an ant target.
    </dd>
    <dt>test-restart1.xargs</dt>
    <dd>
      xargs file for the Knopflerfish test suite. Normally invoked
      via an ant target.
    </dd>
    <dt>test-restart2.xargs</dt>
    <dd>
      xargs file for the Knopflerfish test suite. Normally invoked
      via an ant target.
    </dd>
  </dl>    
</div>

<a name="props"></a>
<h2 class="kf">Framework and System Properties</h2>
<p>
  The behavior of Knopflerfish can be further controlled by specifying
  framework and system properties that are either specified by OSGi or
  Knopflerfish specific. The framework and system properties are
  described in detail in the <a
  href="bundledoc/index.html?docpage=framework/index.html">
  framework bundle documentation </a>.
</p>
<p>
  There is a default properties setting in the <code>props.xargs</code> file.
</p>
